Any update on this?

I'll give it a run through soon. Long-form tutorials require more scrutiny and I want to give this the time it deserves, but we're also trying to get the 0.5 release ready. I'll try to get to this asap.

Thanks for the review @MinerSebas
I like your suggestions very much.
Do I have to do anything?
Resolve them all? Commit something?
Or is that cart's job?

You should apply the suggestions which you agree with.
If you made the change, you can mark those comments as resolved.

I compared the tutorial code to the 0.5 release code. It is very similar.
Would it be an option to accept this pull request and then fix the few differences?

Now that 0.5 is released, we'll want to make sure the tutorial matches the 0.5 release prior to merging. I'm starting my review now.

Thanks Carter. Much appreciated!

Now that bevy 0.5 is out, I believe that it is a good moment to turn some attention to the learn section of the bevy book.
Currently there are only the very basics explained.
Barely more than a hello_world plugin.
I am not trying to disparage the current page, it is a great start and I used it to great success myself.
But I truly believe now is the time to add a page that goes into detail on a real world example:
The truly inspiring breakout example.

First, I apologize for not doing a full review yet. I got distracted by the renderer rework and reviewing other things that definitely take precedence (like bugs / safety issues).

We definitely need to start expanding the book. I've been overly protective of the content we add to it for a long time because I have specific goals for the tone + voice of the writing. But I also haven't had the time (or inclination) to write content myself, so its a bit unfair for me to hold the book hostage indefinitely (and tone / "voice" can be addressed in code reviews).

My biggest concern about the Breakout example (and why I haven't just quality checked the content and merged it) is that it isn't necessarily the best way to introduce Bevy concepts. I want the Bevy Book to intentionally layer on concepts piece by piece. Starting from the idea to "write a tutorial on how to write Breakout" isn't necessarily the best way to teach people what they need to know. As a general rule we should come up with a list of things to teach first, define an order that they should be taught, and then try to write a set of tutorials that cover that content (and maybe generate a complete game ... but that isn't even necessarily a requirement).

Again, this isn't a comment on the quality of the breakout tutorial (which I haven't worked through fully yet), just a general comment on book methodology and how I assign priorities to things.

A "how to write X in Bevy" style of tutorial is at the very least still extremely useful and would be a good blog post. Once I work through it I'll hopefully have an opinion on if it is a good fit for the bevy book.

I'll also link to this in the Bevy discord so we can get more eyes on it / opinions on Bevy Book direction.

This is great work! If we decide not to merge this, please, please contribute this to awesome-bevy @rhulha so others can benefit from it :)

My biggest concern about the Breakout example (and why I haven't just quality checked the content and merged it) is that it isn't necessarily the best way to introduce Bevy concepts.

I agree with this. Progressively growing tutorials can be a great approach, but I don't think this Breakout game is a great choice for that. The code quality isn't optimal (it prioritizes simplicity over good architecture) and doesn't hit all the points we might want.

We definitely need to start expanding the book.

Agreed. I think we should design on a high-level vision for what it should be, write up some style guides and then open it up to contributions. IMO those details are best finalized in an RFC, and then added to this repo's CONTRIBUTING.md.

As a general rule we should come up with a list of things to teach first, define an order that they should be taught, and then try to write a set of tutorials that cover that content (and maybe generate a complete game ... but that isn't even necessarily a requirement).

I agree with this philosophy; this is a great place to start from. A concept map might be a nice place to start planning that?

IMO those details are best finalized in an RFC, and then added to this repo's CONTRIBUTING.md

Yeah I agree with this. I'm cool with using the RFC rfc repo for documentation stuff, as I consider the Bevy Book to be a part of the "Bevy product' as a whole.

Thank you all for your great feedback. I have two comments:

1. Regarding the statement: "I've been overly protective of the content we add to it for a long time because I have specific goals for the tone + voice of the writing."

I completely understand with the voice and tone goals. Please feel free to change any of my jokes or quips if there are any. Or to change anything else. But I also agree with the statement of being overly protective.
I would like to argue that the tutorial I wrote adds more utility to the bevy book and the community than the tutorial not being
there. Could there be a better tutorial coming in the future? Sure. But until then, let's just add this for now.
Please also consider that the bevy book currently points to exactly the breakout game as a next step to look-at here:
https://bevyengine.org/learn/book/next-steps/

So it is hard for me to understand that the breakout code is deemed not great on the one hand, therefor we should not have a tutorial on it, but on the other hand it is fine to have a direct link to the source code without the explaining words from my tutorial.

Unless you believe that my tutorial will misleads users and move them in the wrong direction. I still believe that adding
the tutorial adds more value than not having it there. And I promise if a better tutorial comes along and you delete mine,
I will not have any hard feelings.

2. Regarding the statement: "My biggest concern about the Breakout example (and why I haven't just quality checked the content and merged it) is that it isn't necessarily the best way to introduce Bevy concepts. I want the Bevy Book to intentionally layer on concepts piece by piece. "

I believe I had and have the exact same sentiments and you might be happy to learn, that I did exactly that: Introduce the concepts piece by piece. I did not simply go through the breakout source code and just explain every line of code, no, instead I created 5 new projects all based on the breakout source code.

In each of those new projects I introduce a new concept.

First I start with a breakout example that only has the paddle:
https://gist.github.com/rhulha/0d41043539b979b1da450ee0c745490d
This is a complete self-contained example.

Then if readers want to go on and learn more, in the next step I show how to add the walls:
https://gist.github.com/rhulha/1697c629433896608b9485b6fe112321
Again a complete self-contained example.

Then if readers want to go on and learn more, in the next step I show how to add the ball and the collision system:
Again a complete self-contained example.

Then if readers want to go on and learn more, in the next step I show how to add the bricks:
Again a complete self-contained example.

Finally if readers want to go on and learn more, in the final step I show how to add the Scoreboard using a TextBundle.
This of course then represents the original source code.

I really tried my best to be careful and considerate with a beginners time and expectations of learning, exactly as you said, piece by piece.

This tutorial represents, to the best of my knowledge and experience, the dream tutorial I would be happy to read on any game engine anywhere.

My best whishes,
Ray.

I would like to argue that the tutorial I wrote adds more utility to the bevy book and the community than the tutorial not being there. Could there be a better tutorial coming in the future? Sure. But until then, let's just add this for now.

I can very much see the value in this, especially if we can't get an alternate solution in place for the 0.6 launch. Fundamentally, I'm not sure that much of the existing content will exist after a full revamp, which means that removing more won't make the situation there worse (especially since this content can be migrated).

I'm going to do a full review of this today, let's see if we can get something better up. The return on investment in terms of Bevy's success of better highly-visible tutorial content is extremely high.

P.S. I would very much like to see #83 fixed as we extend the book out more; the maintenance burden of manually testing this code and perils of releasing broken tutorial code are both too high for my comfort.

Alright, review is finished. There's a bunch of small nits that will be easy to address, so I'll focus on the larger stuff here.

1. The code quality of the Breakout game is... not great. Sorry Cart! Things like monolithic setup systems, the unidiomatic way we access the text, the awkwardness around setting the max time step. Those should be cleaned up before we integrate this into the book and further encourage bad habits.
2. The Breakout example is missing some pretty critical patterns that are essential to Bevy games. Namely: code organization practices (modules and plugins and states), events, change detection, audio and asset loading. We could expand the example in the future to get around this, or work to build a new one.
3. I don't love the practice of commenting out lines as we go. IMO this example should be split into three separate pages: paddle and walls only, adding ball + bricks, adding the scoring system. This will also help with length. Don't include dead code, just modify functions later as its needed. At the top of each of those pages, link to a gist or use some sort of code folding to have the complete code for that step shown.
4. Like I mentioned above, we're really going to need to fix Bevy book code should be compiled against new releases #83 and automatically compile and test this code somehow for this to be maintainable in the future. I'm not entirely sure how to best do that. @mockersf, what's your perspective on this question?

Wow, thank you alice-i-cecile,
this was a thorough review..
Your changes and ideas are great!

My only feedback at this moment is, that using git to work on the webpage/tutorial doesn't seem very agile.
I personally would suggest to have something more like a wiki with named write access only.
So you and everyone who is allowed can do direct changes.
I think having to accept and click two buttons for every backtick change is a bit overkill.
But hey, if it works for you guys I am happy as well.

Also, I have to click on "66 hidden items" "load more" wait 3 seconds. Click on two buttons to accept a change request.
And then the whole page reloads and I have to click on "67 hidden items" "load more" again... rinse and repeat.

I am probably too uneducated in the ways of the Github, but this is super annoying.

My apologies @rhulha; I should have just made a PR to your branch. It started off as a quick review, but then it ended up being a comprehensive edit. If you'd prefer, you can just mark my comments as resolved and implement them manually.

The other workflow that can work well if you're collaborating intensively with a few people is to make them collaborators on your fork, which then lets them make commits directly.

Oh no, it's not your fault that Github reloads the page every time I accept a change...

68 bottles of beer on the wall, 68 bottles of beer.
Take one down, pass it around, 69 bottles of beer on the wall...

I'll just comment on @alice-i-cecile points, you're the one who pinged me 👍

1. The goal of the game examples are not "great code quality". In my opinion, it's "good enough quality given the constraints": small number of systems, only one file, nothing too complex.
2. Related to first point. The Breakout example is not meant to be complete. We should do some, there is More complex game examples bevy#1248. Just a complete breakout would be great for that, and would be ton more complex than the existing example
3. I agree. More on that below
4. I'll reply there

I wanted to mention two tutorials for other game engine that I followed:

• Amethyst Pong Tutorial: https://book.amethyst.rs/book/stable/pong-tutorial
  • + At the beginning of Amethyst docs
  • + Nice step by step
  • - Never worked for me when I tried to do it (two different times)
• Godot Your first game: https://docs.godotengine.org/en/stable/getting_started/step_by_step/your_first_game.html
  • - Late in the doc, I actually just skimmed over it after reading everything before
  • - All in one page, not split at all
  • + Doc before that was top, and after reading the first chapters of the step by step (before the game tutorial) I was actually able to pick what I wanted from the doc without reading everything

The goal of the game examples are not "great code quality". In my opinion, it's "good enough quality given the constraints": small number of systems, only one file, nothing too complex.

I think we can improve this significantly within the constraints there still. While they may not be complete, they should be exemplary: worth emulating and learning from in addition to serving as tests. I'll try to get a PR to the main repo for that in though; it's been bugging me for a while.

Related to first point. The Breakout example is not meant to be complete. We should do some, there is bevyengine/bevy#1248. Just a complete breakout would be great for that, and would be ton more complex than the existing example

I agree. This is mostly a mark against taking the approach of adapting one of our existing simple examples to serve as a tutorial. I like the idea of having both a simple and complex breakout a lot!

If it might be useful to hear from an actual beginning Bevy user, I found the breakout example extremely helpful.
I loved that it

• was a real game that was actual fun and engaging to play.
• was using text elements to show the score.
• had collision detection and fun bouncy physics.
• was easy to read and understand even for a Rust and Bevy newbie like me.
• showed and handled different things like graphics, positioning, physics, text and input.

Of course I can't judge if it would be possible to make the breakout source code even better, since I don't know enough about Bevy. But for my personal taste, the example was awesome and gave me a really good first impression of Bevy as an engine, while also showing what was different about it to other engines that I had used in the past. (The Rust things and the cool query syntax come to mind). I liked it so much in fact, that I felt bad, that there was no tutorial using it as its foundation.... And well, the rest is history. :-D

Cheers! I love you all!

I think we can improve this significantly within the constraints there still. While they may not be complete, they should be exemplary: worth emulating and learning from in addition to serving as tests. I'll try to get a PR to the main repo for that in though; it's been bugging me for a while.

It's also helpful to explain why some bit of code is exemplary. For instance, the Rust book has a nice section on some basic refactoring techniques. A tutorial can teach more by starting with something quick/sloppy, and then include refactoring in the tutorial's content.

Some of the changes in bevyengine/bevy#2094 might also make sense as steps in the tutorial!

I like the idea of refining code a lot, and showing the refactoring process. It's very educational, but almost never formally taught.

I've written up an RFC on how to revamp the book now!

Of note, I propose splitting the learning material into two paths: Quick Start and the Bevy Book. A condensed and updated version of a Breakout tutorial would fit well as one of our Quick Start games.

We'll be looking for a refreshed version of something very similar to this as part of a Quickstart Game. See bevyengine/rfcs#23. Thanks for the awesome inspiration!

That will need to be a new effort, basically from scratch to compensate for changes to both the website structure and Breakout code changes though, so I'm going to close this PR out <3